home *** CD-ROM | disk | FTP | other *** search
/ A.C.E. 2 / ACE CD 2.iso / FILES / UTILS / JACOSUB.LHA / JACOsub / documentation / ARexx.doc < prev    next >
Encoding:
Text File  |  1995-03-19  |  7.1 KB  |  198 lines
  1. JACOsub ARexx Communications
  2. ============================
  3.  
  4.  
  5. EXECUTING AREXX SCRIPTS FROM JACOSUB
  6. ====================================
  7.  
  8. You can execute ARexx scripts at specific times in JACOsub scripts while
  9. the JACOsub script is playing.  Simply use the RX directive in a timed
  10. line.  The format of such a line in a JACOsub script is:
  11.  
  12. <start time> <end time> RX <ARexx script name to execute>
  13.  
  14. <end time> is ignored, but should be slightly greater than the start time
  15. to avoid a compiler warning.  See the RX directive in the file JScripts.doc
  16. for more information.
  17.  
  18.  
  19. COMMUNICATING WITH JACOSUB THROUGH AREXX
  20. ========================================
  21.  
  22. JACOsub's ARexx port is called 'JACOsub' (note the capitalization).  The
  23. program accepts several different commands through its ARexx port.  They
  24. are described below, grouped into the categories of file commands, script
  25. play commands, and editor commands.  Examples of usage for file commands
  26. and script play commands may be found in the rexx subdirectory.
  27.  
  28.  
  29. ARexx file commands
  30. -------------------
  31.  
  32. 'LOADSCRIPT' FILENAME/A
  33.  
  34.    Load a script called FILENAME into memory.  FILENAME should end with an
  35.    appropriate script extension (such as ".js").  RESULT is returned as
  36.    0=success, 1=failure.
  37.  
  38. 'SAVESCRIPT' FILENAME/A
  39.  
  40.    Write the script currently in memory to a file using the name FILENAME.
  41.    RESULT is returned as 0=success, 1=failure.
  42.  
  43. 'QUIT'
  44.  
  45.    Terminate JACOsub, remove from memory.  No return value.
  46.  
  47.  
  48. ARexx script play commands
  49. --------------------------
  50.  
  51. 'BEGINTIME' TIME/A UNITS/N
  52.  
  53.    Set the begin time for playing a script.  TIME is a string such as
  54.    "0:04:35.18", UNITS are optional units per second, describing the
  55.    numbers behind the decimal point in TIME (default UNITS is whatever is
  56.    current in JACOsub).  RESULT is returned as 0=success, 1=bad TIME
  57.    format, or 2=TIME decimal fraction conflicted with UNITS.
  58.  
  59. 'NEXTVIEW'
  60.  
  61.    To be called after PLAYSTART, but only if PLAYSETUP was called with the
  62.    argument AREXXTRIGGER.  This command causes the play screen to switch to
  63.    the next view.
  64.  
  65. 'PLAYSETUP' [TRIGGER/A]
  66.  
  67.    Set up program for playing a script.  Script will be compiled if needed.
  68.    RESULT is returned as 0=ready to begin playing, 1=failure.
  69.  
  70.    The optional argument TRIGGER defaults to the value INTERNAL, which is
  71.    normal play using the internal clock.
  72.  
  73.    If TRIGGER is set to AREXX, then JACOsub will expect to receive
  74.    'NEXTVIEW' commands for triggering each switch to the next screenful of
  75.    titles.  This is sort of like the manual step-play mode, only via ARexx.
  76.    It is important to know that short duration blank screens in between
  77.    titles also count as screens that must be triggered.
  78.  
  79.    If TRIGGER is set to EXTERNCLOCK, then JACOsub will expect to receive
  80.    timer data from a timecode reader.  THIS FEATURE IS NOT YET IMPLEMENTED.
  81.    For now, this setting behaves the same as INTERNAL.
  82.  
  83.    Any triggering mode will still accept the ESC keystroke to abort play. 
  84.  
  85. 'PLAYSTART'
  86.  
  87.    Start the script playing.  This command should be sent *only* after
  88.    successful execution of PLAYSETUP.  RESULT is returned as 0=success,
  89.    1=failure.
  90.  
  91. 'ABORTPLAY'
  92.  
  93.    Stop the script play, close play screen.  This command has no effect if
  94.    no script is currently playing.  There is no return value.
  95.  
  96. 'SCREENTOBACK'
  97.  
  98.   If the play screen exists, hide it behind the Workbench.  There is no
  99.   return value.
  100.  
  101. 'SCREENTOFRONT'
  102.  
  103.   Make sure the play screen is completely visible (if it exists).  There is
  104.   no return value.
  105.  
  106.  
  107. ARexx editor commands
  108. ---------------------
  109.  
  110. JACOsub maintains a "current line" pointer for ARexx.  The initial value is
  111. the top line of the script.  The WHICHLINE argument in these commands
  112. specifies on which line the command should operate.  The allowed values
  113. that may be passed for WHICHLINE are:
  114.  
  115.    CURRENT       Current line.  The current line pointer is not changed.
  116.    NEXT          Next line.  Command will fail with RESULT=1 if there
  117.                  is no next line, otherwise the current line pointer is
  118.                  changed to the next line.
  119.    TOP           Top line.  Current line pointer is changed to the top.
  120.    line number   Row in the editor.  Command will fail with RESULT=1 if the
  121.                  line does not exist in the script, otherwise the current
  122.                  line pointer is changed to the specified line.
  123.  
  124. All editor commands return RESULT as 0=success, 1=failure.  An editor
  125. command may fail for two reasons: specified line does not exist, or memory
  126. could not be allocated.  In any case, here are the commands:
  127.  
  128.  
  129. 'APPENDLINE' TEXT/A
  130.  
  131.    Append a line containing TEXT to the end of the script.  The current
  132.    line pointer is updated to point to this new line.
  133.  
  134. 'DELETELINE' WHICHLINE/A
  135.  
  136.    Delete the specified line.  The current line pointer is advanced to the
  137.    line that follows the one to be deleted, if it was deleted successfully.
  138.  
  139. 'GETLINE' WHICHLINE/A
  140.  
  141.    This command copies the specified line into a variable called JSTEXT and
  142.    returns it as a result, in addition to the RESULT code.
  143.  
  144. 'GETROW'
  145.  
  146.    The current line number is returned in RESULT.
  147.  
  148. 'INSERTLINE' WHICHLINE/A TEXT/A
  149.  
  150.    Insert a line containing TEXT in front of the specified line.
  151.  
  152. 'REPLACELINE' WHICHLINE/A TEXT/A
  153.  
  154.    Replace the specified line with a line containing TEXT.
  155.  
  156. 'SETCURRENTLINE' WHICHLINE/A
  157.  
  158.    Move the current line pointer to the specified line.  You will probably
  159.    not have to use this command, because the others also contain a current
  160.    line setting.
  161.  
  162.  
  163. CONTROLLING THE GVP G-LOCK OR THE NEWTEK VIDEO TOASTER
  164. ======================================================
  165.  
  166. Unlike the SuperGen, which JACOsub can control directly, performing
  167. dissolves with the GVP genlock and the Toaster genlock must be done through
  168. ARexx.  If you have configured JACOsub so that the GENLOCK setting is GVP
  169. or TOASTER, then JACOsub will look for a script called gvpfade.jsrx (for
  170. the GVP) or toasterfade.jsrx (for the Toaster) and copy it to
  171. ram:glfade.jsrx for faster execution at the appropriate times.  The
  172. original ARexx script should be located in JACOsub's rexx subdirectory, or
  173. the current directory, or in the rexx: directory.
  174.  
  175. This script is currently not provided.  If you want to write your own
  176. gvpfade.jsrx script, here are the specifications.
  177.  
  178. <scriptname>.jsrx BVAL/N BTIME/N GVAL/N GTIME/N
  179.  
  180. where
  181.    <scriptname> can be gvpfade or toasterfade.
  182.    BVAL  is the background video intensity value at which the dissolve
  183.          should finish.  This actually represents "blackness."  Minimum
  184.          value is 0 for full video, maximum is 63 for full black.
  185.          JACOsub assumes the genlock's BVAL=0 at the start of script play.
  186.    BTIME is the length of the background dissolve in frame counts (there
  187.          are 120 frames per second in NTSC video).  A value of -1 means to
  188.          ignore the BVAL setting.
  189.    GVAL  is the foreground graphic overlay intensity at which the dissolve
  190.          should finish.  Minimum value is 0 (completely transparent),
  191.          maximum value is 63 (completely opaque).
  192.          JACOsub assumes the genlock's GVAL=63 at the start of script play.
  193.    GTIME is the length of the graphic overlay dissolve in frame counts.  A
  194.          value of -1 means to ignore the GVAL setting.
  195.  
  196.  
  197. End of ARexx.doc.
  198.